Skip to main content

AWS - RDS PostgreSQL

RDS PostgreSQL agent setup

DBtune offers a database monitoring agent that operates within your network, securely transmitting metric data to DBtune and applying new proposed configurations. Additionally, the agent is available as a ready-to-use Docker image hosted on public repositories.

Required permissions

Before starting the DBtune agent, you need to make sure that the following prerequisites are met:

  • Create DBtune user in RDS PostgreSQL
CREATE USER dbtune WITH PASSWORD '{dbtune_password}';
  • Grant the necessary permissions to the DBtune user
GRANT pg_monitor TO dbtune;

AWS IAM permissions

The AWS credentials provided to the agent need at least the following permissions:

rds:DescribeDBInstances
rds:ModifyDBParameterGroup
cloudwatch:GetMetricStatistics
ec2:DescribeInstanceTypes
pi:GetResourceMetrics (if Performance Insights is enabled)
rds:RebootDBInstance (if you want to perform tuning with restart)

Setting up the agent

There are multiple ways to run the DBtune agent, below is an example using Docker container:

docker run --detach \
-e DBT_POSTGRESQL_CONNECTION_URL={connection url to the database} \
-e DBT_RDS_DATABASE_IDENTIFIER={rds_database_identifier} \
-e DBT_RDS_PARAMETER_GROUP_NAME={parameter_group_name} \
-e DBT_AWS_ACCESS_KEY_ID={aws_access_key_id} \
-e DBT_AWS_SECRET_ACCESS_KEY={aws_secret_access_key} \
-e DBT_AWS_REGION={aws_region} \
-e DBT_DBTUNE_SERVER_URL=https://app.dbtune.com \
-e DBT_DBTUNE_API_KEY=your-api-key \
-e DBT_DBTUNE_DATABASE_ID=your-database-id \
public.ecr.aws/dbtune/dbtune/agent:latest --rds

Visit the DBtune agent repository for more information.

Environment variables

VariableDescription
DBT_POSTGRESQL_CONNECTION_URLConnection URL to the RDS PostgreSQL database.
DBT_RDS_DATABASE_IDENTIFIERIdentifier of the RDS instance you want to optimize.
DBT_RDS_PARAMETER_GROUP_NAMEName of the parameter group for the instance.
DBT_AWS_ACCESS_KEY_IDAWS access key ID that DBtune will use to authenticate with AWS services.
DBT_AWS_SECRET_ACCESS_KEYAWS secret access key that DBtune will use to authenticate with AWS services.
DBT_AWS_REGIONAWS region where your database is located.
DBT_DBTUNE_SERVER_URLURL of the DBtune server
DBT_DBTUNE_API_KEYYour DBtune API key for authentication.
DBT_DBTUNE_DATABASE_IDDatabase ID assigned by DBtune for this database instance.

Parameters tuned

The parameters tuned by DBtune change with respect to the chosen tuning mode. Below are the two tuning modes supported.

Reload-only tuning mode

This tuning mode tunes without restarting the database server and using only reloads. This does not cause any downtime and is suitable for critical production environments.

The following parameters are tuned in this mode:

  1. work_mem
  2. random_page_cost
  3. seq_page_cost
  4. checkpoint_completion_target
  5. effective_io_concurrency
  6. max_parallel_workers_per_gather
  7. max_parallel_workers
  8. max_wal_size
  9. min_wal_size
  10. bgwriter_lru_maxpages
  11. bgwriter_delay

Restart tuning mode

Most of our user base prefer reload-only tuning to avoid disruptions in production. If your system can handle restarts gracefully and you want to tune more parameters, you can choose this mode which restarts the database up to 30 times in a span of few hours; This will likely deliver additional performance. The following parameters are tuned in this mode in addition to the parameters tuned in the reload-only mode:

  1. shared_buffers
  2. max_worker_processes

Optimization objectives

The recommended objective to use is average query runtime (AQR), which DBtune will minimize as it suggests configurations. For additional metrics, please refer to our section on choosing an alternative optimization objectives.

Agent monitoring stats

info

DBtune only retrieves performance metrics from the database and AWS metric providers, it does not access or transmit any sensitive data, e.g., metadata and the tables data are not transferred.

Below is the data DBtune collects and sends to the DBtune server every second. It gathers these metrics by reading from system tables, as well as calling the AWS metric providers.

Collected data
CategoryMetrics
Database performanceQuery runtime, Transactions per second, Active connections, Cache hit ratio, Wait events, Autovacuum count
SystemDatabase size, Server Uptime
HardwareCPU utilization, Memory usage, Freeable memory

DBtune queries system metrics to ensure production safety. This takes place in 5 second intervals.